home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / doc / uim-common / UIM-SCM < prev    next >
Encoding:
Text File  |  2008-02-15  |  3.4 KB  |  107 lines
  1. This document describes usage of the uim-scm API and facility for
  2. developers.
  3.  
  4.  
  5. * Abstract
  6.  
  7.   The uim-scm API is responsible for following two roles.
  8.  
  9.   - Provides Scheme interpreter interfaces to input method plugin
  10.     developers
  11.  
  12.   - Abstracts Scheme interpreter implementation and narrows its
  13.     interfaces to provide switcheable base of libuim
  14.  
  15.   Other developers should not use this API since the API easily causes
  16.   fatal crash involving GC if you does not pay attention enough. Be
  17.   careful.
  18.  
  19.  
  20. * Protecting lisp objects from GC
  21.  
  22.   uim-scm provides the lisp object type named 'uim_lisp'. Since all of
  23.   the objects are managed by a conservative mark and sweep GC, you
  24.   have to protect them from undesirable collection. The word
  25.   'protection' means that instructing GC "It's in use, don't
  26.   mark". There are two methods of protection.
  27.  
  28.   1. static storage protection
  29.  
  30.     You can allocate arbitrary static storage as for uim_lisp by
  31.     uim_scm_gc_protect(). The function must be invoked before using
  32.     the variables.
  33.  
  34.  
  35.     static uim_lisp foo;
  36.     static uim_lisp bar;
  37.  
  38.     void
  39.     uim_plugin_instance_init(void) {
  40.       uim_scm_gc_protect(&foo);
  41.       uim_scm_gc_protect(&bar);
  42.     }
  43.  
  44.  
  45.   2. stack protection
  46.  
  47.     You can also protect your lisp objects on stack (i.e. auto
  48.     storage). See following example.
  49.  
  50.     char *
  51.     literalize_string(const char *str)
  52.     {
  53.       uim_gc_gate_func_ptr func_body;
  54.       void *ret;
  55.  
  56.       func_body = (uim_gc_gate_func_ptr)literalize_string_internal;
  57.       ret = uim_scm_call_with_gc_ready_stack(func_body, (void *)str);
  58.  
  59.       return (char *)ret;
  60.     }
  61.  
  62.     static char *
  63.     literalize_string_internal(const char *str)
  64.     {
  65.       uim_lisp form;
  66.       char *escaped;
  67.  
  68.       form = uim_scm_list2(uim_scm_make_symbol("string-escape"),
  69.                            uim_scm_make_str(str));
  70.       escaped = uim_scm_c_str(uim_scm_eval(form));
  71.  
  72.       return escaped;
  73.     }
  74.  
  75.     All function that uses stack-placed uim_lisp must be called via
  76.     uim_scm_call_with_gc_ready_stack() as above. It setups the base address of
  77.     'protected' stack region. In this case, the lisp objects 'form', anonymous
  78.     return value of uim_scm_make_symbol(), uim_scm_make_str() and
  79.     uim_scm_eval() are protected by the method (although some objects may be
  80.     placed into registers, the registers are also protected implicitly).
  81.  
  82.     The function type uim_gc_gate_func_ptr is defined as follows in
  83.     uim-scm.h. Since its arguments and return type are fixed to (void *),
  84.     passing multiple arguments to a function need temporary struct. See
  85.     uim_scm_error() in uim-scm.c for example.
  86.  
  87.     typedef void *(*uim_gc_gate_func_ptr)(void *);
  88.  
  89.     The 'protected' stack region can be
  90.     nested. i.e. uim_scm_call_with_gc_ready_stack() can be invoked from a
  91.     function invoked from uim_scm_call_with_gc_ready_stack().
  92.  
  93.  
  94. * Internal
  95.  
  96.   The uim-scm API is not intended to provide all R5RS features. Only 'core'
  97.   ones to write Scheme-C adapters should be added. Consider how
  98.   frequently it will be used, and whether it should be written by C,
  99.   when you want to add an API function.
  100.  
  101.   Current implemenation of uim-scm only provides the SigScheme interpreter. To
  102.   avoid namespace pollution, all SigScheme functions and variables are defined
  103.   as static and wrapped into uim-scm.c by direct inclusion rather than linked
  104.   via public symbols. After elaboration of uim-scm API, the Scheme interpreter
  105.   implementation can be switched to another one such as uim-scm-scheme48.c or
  106.   uim-scm-gauche.c.
  107.